 /*******************************************************************************
  * Copyright (c) 2000, 2006 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  * IBM Corporation - initial API and implementation
  *******************************************************************************/
 package org.eclipse.ui.views.properties;

 import org.eclipse.jface.viewers.CellEditor;
 import org.eclipse.swt.graphics.Image;
 import org.eclipse.swt.widgets.Composite;

 /**
  * <code>IPropertySheetEntry</code> describes the model interface for the
  * property sheet.
  * <p>
  * May be implemented when supplying a custom root entry to a property page.
  * </p>
  */
 public interface IPropertySheetEntry {

     /**
      * The filter id for expert properties
      */
     public String FILTER_ID_EXPERT = "org.eclipse.ui.views.properties.expert"; //$NON-NLS-1$

     /**
      * Adds the given listener to this entry's collection of listeners.
      *
      * @param listener
      * the listener to add
      */
     public void addPropertySheetEntryListener(
             IPropertySheetEntryListener listener);

     /**
      * Apply the current cell editor value.
      */
     public void applyEditorValue();

     /**
      * Called when the entry is no longer needed
      */
     public void dispose();

     /**
      * Returns the entry's category.
      *
      * @return the entry's category
      */
     public String getCategory();

     /**
      * Returns the child entries for this entry.
      *
      * @return the child entries for this entry
      */
     public IPropertySheetEntry[] getChildEntries();

     /**
      * Return a short description of the property sheet entry. Typically this
      * description is shown in a status line when the entry is selected.
      *
      * @return the entry's description
      */
     public String getDescription();

     /**
      * Returns the name used to display the property.
      *
      * @return the name used to display the property
      */
     public String getDisplayName();

     /**
      * Return the <code>CellEditor</code> used to edit the property.
      *
      * @param parent
      * the parent widget for the editor
      * @return the <code>CellEditor</code> used to edit the property
      */
     CellEditor getEditor(Composite parent);

     /**
      * Returns the error text to display if the value is invalid.
      *
      * @return the error text to display when the value is invalid or
      * <code>null</code>
      */
     public String getErrorText();

     /**
      * Return the filter ids used to group entries into levels such as Expert.
      * Valid values are defined as constants on this interface.
      *
      * @return the filter ids used to group entries into levels such as Expert.
      */
     public String [] getFilters();

     /**
      * Returns the help context id for this entry, or <code>null</code> if
      * this entry has no help context id.
      * <p>
      * NOTE: Help support system API's changed since 2.0 and arrays of contexts
      * are no longer supported.
      * </p>
      * <p>
      * Thus the only valid non- <code>null</code> return type for this method
      * is a <code>String</code> representing a context id. The previously
      * valid return types are deprecated. The plural name for this method is
      * unfortunate.
      * </p>
      *
      * @return the help context id for this entry
      */
     public Object getHelpContextIds();

     /**
      * Returns the image for the property value, if there is one. This image is
      * managed by the entry it came from. Callers of this method must never
      * dispose the returned image.
      *
      * @return the image for this property value or <code>null</code>
      */
     public Image getImage();

     /**
      * Returns the value of the objects expressed as a String.
      *
      * @return the value of the objects expressed as a String
      */
     public String getValueAsString();

     /**
      * Returns <code>true</code> if the entry has children.
      *
      * @return <code>true</code> if the entry has children
      */
     public boolean hasChildEntries();

     /**
      * Removes the given listener from this entry's collection of listeners.
      *
      * @param listener
      * the listener to remove
      */
     public void removePropertySheetEntryListener(
             IPropertySheetEntryListener listener);

     /**
      * Resets the property value to its default value if it has been changed.
      * <p>
      * Does nothing if the notion of a default value is not meaningful for
      * the property.
      * </p>
      */
     void resetPropertyValue();

     /**
      * Sets the objects which represent the property values for this entry. In
      * the case of the root entry these objects are the input to the viewer.
      *
      * @param values the values for this entry
      */
     public void setValues(Object [] values);
 }

